Aminet 2/Aminet AMIGA CDROM (1994)(Walnut Creek)[Feb 1994][W.O. 44790-1].iso/Aminet/util/gnu/emacs_src.lha/emacs-18.58/amiga.doc

Lisp/Scheme | 1992-10-01 | 22KB | 566 lines

1. Introduction
---------------

Emacs is a powerful, but sometimes cryptic, editor. In this Amiga
version, I have tried to make it easier to use with menus, mouse
support and arrow key support, but it still requires some getting used
to. I would recommend starting with the tutorial, which can be started
from the Help menu (if it is missing, you didn't install emacs
correctly. Check that the file s:.emacs-menu.el exists) or from the
keyboard by typing Control-H and then t.

This file only describes the Amiga specific features of emacs, and it
assumes a working knowledge of emacs. For more documentation you can
consult the emacs help (Information in the Help menu, or C-h i) or
read the emacs manual (which is the same document in a printed form).
This manual can be bought from the

     Free Software Foundation
     675 Mass Ave
     Cambridge, MA 02139
     USA

See the file gnuemacs:etc/DISTRIB for more information (you can type
C-h C-d to view it).

To install emacs, read the file INSTALLATION.


2. Changes since the last version
---------------------------------

Several features have been added since v1.25:

- workbench support.
- asynchronous processes can be run in emacs, so the shell & compile
  commands now work.
- startup problems (missing libraries, no memory, etc) should now
  be reported (there is one exception: if run under any version
  before 2.04, emacs will fail silently).
- the emacs window can be configured in s:.emacs without causing
  nasty visual effects (the window opens directly where you wanted,
  with the correct size, fonts, etc).
- the numeric keypad keys can now be defined separately from the
  equivalent keys on the main keyboard.
- the 'ctrl-g' interrupt key now works far better (it can
  interrupt run-away lisp code).
- the -t startup option has been renamed as -dev.
- the keyboard sequences generated for amiga specific features
  (eg function & arrow keys) have changed (these used to start
  with C-\. This has been replaced by the C-x C-^ sequence, for
  very good reasons).
- last redisplay bug squashed !

Numerous other bugs have also been destroyed ...


3. Using emacs in a window
--------------------------

Emacs runs in a window on the Workbench (this can be changed). It
basically works like just any other version of GNU Emacs, using the
same keys, etc. It uses the standard amiga keymap, but with some strange
modifications:

o The left alt key is stolen as a meta key for emacs. This means you can't use
it to enter accents. However, the right alt key remains untouched. Hence
'left alt-f e' moves forward one word and inserts an e, while
'right alt-f e' inserts an e acute. In the rest of the text, the meta key
always means the 'left alt' key.

o C-space is always mapped to C-@, the set-mark command, for convenience.

o The backspace key always sends DEL (delete previous character in emacs),
and DEL sends C-d (delete character under cursor). If you don't like this,
add the line
    (setq amiga-remap-bsdel nil)
to your .emacs file (in s:).

o Keypad keys are prefixed with C-x C-^ K (so 0 generates C-x C-^ K 0).
Normally, C-x C-^ K is a do-nothing operation, so the keypad keys just
insert the usual character. If you want to redefine the keypad keys, you
must do the following:

  (global-set-key "\C-x\C-^K" (make-sparse-keymap))
  (global-set-key "\C-x\C-^K0" '<function for key 0>)
  (global-set-key "\C-x\C-^K1" '<function for key 0>)
  ...

Once you have redefined one key, you must define all of them (as C-x C-^ K
is no longer a do-nothing command). If you still want a keypad to insert
its usual character, you can use (for +)

  (global-set-key "\C-x\C-^K+" 'self-insert-command)

o The sequences for function & arrow keys are the standard Amiga ones,
except that the initial character (CSI, code 155) is replaced by
C-x C-^. For example, F1 is C-x C-^ 0 ~. You can always find the
characters generated by a key by pressing it, and then executing
M-x view-lossage. This displays the last 100 characters seen by emacs. So
to define F1 to be view-lossage you would add

  (global-set-key "\C-x\C-^0~" 'view-lossage)

to s:.emacs (trying to define F1 interactively with M-x global-set-key
will fail ...).


There are several extra features:

a) Mouse support, similar to the X-Windows version.

You can position the cursor with the left mouse button. Other possibilites are:

action            result
------------------------------
shift-left button    set mark at mouse position
control-left button    cut between point and mouse position
meta-left button    copy between point and mouse position
middle button        paste
shift-middle button    iconify emacs window (double click to deiconify)

Some of the control, meta, etc combinations may be stolen by Intuition or
commodities programs, so don't be surprised if they don't all work.

All of these actions may be redefined (this is emacs after all!), see the
file lisp/amiga-mouse.el for details (you will need to learn lisp if you don't
already know it ...) [Note: this file is not included in the binary only
distribution, you will need the source code version].

b) Clipboard

At first glance, emacs uses the Amiga clipboard, ie it cuts to the
clipboard and pastes from it (via the menu operations or the C-w
(kill-region), M-w (copy-region-as-kill) & C-y (yank) commands).

Things are actually complicated by emacs use of a "kill ring" (ie it
remembers the last 30 things cut. The M-y (yank-pop, menu command
Paste Previous) allows you to recover old cuts):

- When you cut (or copy) something in emacs it is placed in the
clipboard.

- When you paste (yank) something in emacs, it checks the clipboard to
see if it contains anything new. If so, it pastes that.

[Note: It also checks the clipboard when you cut something, and saves
that in the kill-ring if necessary]

All this effort is used to make the clipboard appear to operate
transparently in emacs.

c) Window

By default, emacs runs in a window on the workbench screen using the
system default font and the standard colours. All this can be changed:

o The font can be specified with the -fn <font> <size> option when you
run emacs. You can also use the amiga-set-font command interactively,
or add a line like
   (amiga-set-font "topaz" 11)
to your s:.emacs file. The font must be non-proportional.

o The window size and screen can be changed with the
amiga-set-geometry function. It takes 4 or 5 parameters, the (x,y)
position of the window and its (width,height). The last optional
parameter specifies the screen: a string gives the name of a public
screen, t stands for the default public screen (normally the
workbench) and nil means keep the same screen. For example, the lisp code
  (amiga-set-geometry 0 0 640 400)
resizes the emacs window to 640x400. If the screen would be too small
given the current font (there must be room for 11x4 characters), the
change is refused.

To use a public screen requires an utility to create them ...

o The foreground & background colours can be changed with the
amiga-set-foreground-color & amiga-set-background-color commands. You
specify the pen and not the actual colour (from 0 to 7 only,
because of restrictions in console.device).

o The emacs window can be iconified (onto the workbench) with the
amiga-iconify command. This is bound to shift-middle button on a 3
button mouse, and to C-z (which is normally bound to suspend-emacs,
which doesn't work on the Amiga).

To deiconify emacs, double click on the icon.

[Note: in this version, emacs will continue to answer to ARexx
commands while iconified. The variable amiga-emacs-iconfied is
set to 't' while emacs is iconified, 'nil' the rest of the time.
You can test this, eg to make sure that emacs is not iconified
before reading some user input]

If you use the functions described above in s:.emacs, they will take
effect before emacs's window is opened. This will avoid the nasty
visual effects of the previous version.

d) Menus

If you have installed emacs correctly (see the INSTALLATION file), it
will startup with some menus containing some useful basic
functions (the layout was inspired from that of TurboText, another
good editor which has the disadvantage of being more expensive than
emacs ...). Alongside each item is the emacs key sequence which
invokes that function, if any.

Using the Menu Help functionality of AmigaDOS 2.04, you can get help
on any menu item by highlighting it with the mouse and pressing the
Help key [This is easier if you're left handed :-)].

The menus are not fixed, they are defined by the s:.emacs-menu.el file
(which isn't human-readable). To modify them, edit s:.emacs-menu.menu.
This contains a lisp-like (but quite legible even for lisp-haters)
representation of the menus, which you can modify by adding items or
menus. The format should be obvious (just make sure that closing
brackets correspond to the correct opening ones, emacs always shows
the corresponding '(' when you type a ')'. Also the last bracket
should correspond with the first).

When you have finished your changes, type C-c C-c. This will save your
menus, and then generate a .el file from them (this takes several
seconds even on an A3000. Be patient). Then save the resulting file.
To have the new menus take effect immediately, type M-C-x while in the
.el file.

Enterprising lisp programmers can customise the menus even more by
modifying the functions amiga-menus-dispatch and/or amiga-menus-help
in lisp/amiga-mouse.el. This code basically receives a (menu-number
menu-item-number) list and must take the appropriate action
(currently, execute the command associated with that particular menu
item). The lack of comments will surely not deter these audacious
pionneers ...

e) Command line options

Beyond the standard emacs command line options (for which
documentation tends to be rather sketchy, not to say missing), you can
also use:

-prealloc <n>: Reserve n bytes of memory for emacs exclusively. This
option *must* be the first on the command line. On the A3000, chip
memory can't be used for emacs (the details are complicated ...), so
you will run out of memory sooner than expected. This option allows
you to reserve some for emacs before it gets eaten by other programs.

-fn <font> <size>: Set the font that emacs uses, like the
amiga-set-font command (see section c, on windows). Note that there
must be enough room for 11x4 characters in the standard 640x200
window. So avoid fonts bigger than 40 points ...

-nw: Don't use a window, use a serial port. See part 3, Using Emacs
over a serial line.

f) ARexx

Emacs has a full ARexx interface. It can execute scripts and commands
synchronously (waiting for the result) or asynchronously, and has an
ARexx port from which it accepts commands.

To execute a script, you use the amiga-arexx-do-command (synchronous)
or amiga-arexx-send-command (asynchronous) commands. These ask for the
script file name (the default extension is .elx). If you just want to
execute a simple ARexx command, you can prefix those commands with C-u
and specify the string to execute.

From lisp, you must use
  (amiga-send-command "<file>" nil) for a script, and
  (amiga-send-command "<commands>" t) for direct execution.
(and the same for amiga-do-command). The result of amiga-send-command
is an integer that can be passed to amiga-arexx-wait-command to wait
for the completion of the script or command. It can also be used with
amiga-arexx-check-command to check if the script has finished. For
example:

  (let ((arexx-id (amiga-send-command "start-fun" nil)))
    ... do something here ...
    ; and wait for arexx script to end
    (amiga-arexx-wait-command arexx-id))

Emacs's ARexx port accepts commands in lisp, and is usually called
EMACS1 (if you run emacs twice simulatenously, the second one will
have EMACS2, and so on). For example (from a shell),

  rx "address EMACS1 '(beginning-of-buffer)'"

will set point to the beginning of the buffer.

ARexx commands are only processed at certain times, so be careful how
you design your applications. These are:

o While waiting for commands from the keyboard (ie when emacs is
idle or iconified).
o While processing a synchronous (amiga-arexx-do-command) script or
waiting for a script to terminate with amiga-arexx-wait-command.
o When the amiga-arexx-process function is called.

They also affect the user visible state by default (ie calling
beginning-of-buffer as above modifies the user's position). Avoid
sending random commands at random times, or use save-excursion.

As usual, all this behaviour can be modified to some extent. Look in
amiga-init.el for details [The source code is the documentation...].

I still haven't written any significant examples, so ...

g) Workbench support

Beyond iconification (see the section on the emacs window), emacs
supports a number of features for Workbench users:

- emacs can be run from the Workbench, by all the usual methods
  (double clicking on the tool, double clicking on a project which
  has temacs as its default tool, etc). All the projects that are
  passed to temacs will be loaded (if they are files), or listed
  with dired (if they are directories).

- icons can be dropped in emacs's window, the corresponding file
  or directory will be loaded or listed.

- icons can be created for files that are saved. This is the default
  when emacs is run from the workbench. This is controlled by the
  amiga-create-icons variable: if you always want icons to be
  created, add

    (setq amiga-create-icons t)

  to s:.emacs, or

    (setq amiga-create-icons nil)

  if you never want them.

h) external processes

This version of emacs fully supports synchronous (used to get the
result of ls for dired, for instance) and asynchronous (as in the
'shell' command) processes. However, it requires Matt Dillon's
'fifo.device' and 'fifo:' devices to function. See the INSTALLATION
file for details.

This allows full support for all emacs functions which call external
programs, providing that said programs exist on the Amiga. The
following work:
  compile (for SAS C 5.10b, with a few occasional problems)
  grep
  shell (but see the discussions below)
  display-time
  dired
  list-directory
  sort-...

The compile command sometimes has problems finding file names in the
error messages, and tries to read the current directory instead. If
you are patient, it moves on to the next file.

Because of differences between AmigaDOS & Unix, sending signals (eg
interrupt, kill) to processes is not very reliable. The following
points must be kept in mind:

- In some unlikely cases, the appropriate process to signal won't be
  found.
- The stop-process & continue-process functions don't work.
- interrupt-process & quit-process send a ctrl-c & ctrl-d to the
  process and all its children (probably).
- kill-process also sends a ctrl-c & ctrl-d. It then pretends that
  the process has died.

All input sent to a process after an end-of-file is ignored. The process
just sees an endless sequence of end-of-files. This is most visible with
the shell command, where if you send an end-of-file to a program (eg type)
with C-c C-d, the shell will exit. The bug is in fifo.device, not in emacs.

The input & output of processes run inside emacs look like interactive
files (which allows, for instance, shells to run correctly). However, this
confuses some programs which expect all interactive files to be Amiga
consoles and causes them to crash. Several versions of ls suffer from this
problem (they run into problems while trying to get the window size).

amiga-process-stack-size is the size of the stack for new processes. If it
is 0 (the default), emacs's stack size is used.


4. Using emacs over a serial line
---------------------------------

To use emacs over a serial port, you must do:

  setenv TERM <terminal type> (eg vt100)
  emacs -nw

The setenv line can be put in your User-Startup, so as to avoid typing
it every time.

Emacs cannot simply guess how your terminal works from its name, it
needs a description of it. This is found in a termcap file, which
emacs looks for in s:termcap. If you didn't install this file with emacs,
you can do so by typing (in a CLI):

  join gnuemacs:etc/termcap.ucb gnuemacs:etc/termcap.amiga as s:termcap

[Note: These files only come with the source version]

The -nw prevents the use of a window.

If you have several serial ports, you can type

  emacs -dev ser2.device 2

to use port 2 of device ser2.device. Use of the -dev option implies -nw.

These options (-dev & -nw) *must* be specified at the start of the
command line.

The descriptions of the Clipboard, the command line options and the
ARexx port in part 2 above also apply to use over a serial port.


5. Redumping emacs [This section for expert users only]
-------------------------------------------------------

Enterprising users may want to change the lisp files which are loaded
into the Emacs dump file. The procedure for doing this is very similar
to that with the Unix version, except that the amount of pure storage
can be changed without recompiling emacs. This will allow users
without SAS C v5.10b to still make such changes.

The necessary lisp files are only included in the source distribution,
so you will have to get that first. Once that is available, that you
have made all your changes (eg adding some extra files to be dumped),
use the following sequence to redump emacs:

  cd gnuemacs:etc
  stack 20000
  /temacs -pure <n> -malloc <m> -nl -batch -l loadup dump

The -pure <n> and -malloc <m> options should only be necessary if you
add extra files to be dumped, see below how to choose values for n &
m. The above order for the parameters must be preserved. Specifying
dump without -nl & -batch will have unpredicatable consequences.

Once all the files are loaded, a new copy of gnuemacs:etc/EMACS-DATA
will be saved, and all should work correctly. If you get one of the
following messages:

  Pure Lisp storage exhausted

  Emacs dump: ran out of memory for malloc.

read the following description of the -pure & -malloc options:

When emacs is dumped, it saves (amongst other things) the copies of
two zones of memory, called the pure storage area and the malloc hunk.
These contain an internal representation of the lisp code, so the more
code you include in a dumped emacs, the bigger these need to be. The
default sizes of these are reasonable sizes for the standard lisp code
which is dumped, but you will probably need to increase them if you
add some more lisp modules. The best way to find the new values for n
(size of pure area) and m (size of the malloc hunk), is to run the
command

  cd gnuemacs:etc
  stack 20000
  /temacs -pure 200000 -malloc 200000 -nl -batch -l loadup dump

(these sizes should be largely sufficient, but if you still get one of
the two error messages above, increase them). Then run emacs as usual,
and look at the values of the 2 lisp variables

     pure-bytes-used
and  amiga-malloc-bytes-used

pure-bytes used contains the minimum value for n, and
amiga-malloc-bytes-used the minimum value for m. Add 1000 to these for
luck to get values for n and m, and redump emacs using these.

For those who are into modifying the C source, the default values are
130000 for n (see DEF_PURESIZE in s-amiga.h) and 92000 for m (see
MALLOC_HUNK_SIZE in amiga.h).

6. Source
---------

Source for emacs and all the programs included with it should be
obtainable from the same place as this file. If not, please send me
mail (if you are on the Internet) and I will provide the missing
pieces. Specifically, there should be:

- The emacs sources
- Sources for the 'unix library' needed to compile emacs
- Source for the programs in the c directory (ls, sort, rmdir, grep).
This consists of the GNU fileutils, textutils and grep packages.

Distributing the binary without these packages is a violation of
the GNU General Public License (see the file COPYRIGHT in the etc
directory) under which emacs is distributed.

7. Thanks & Problems
--------------------

I would like to thank the following people for their help while debugging
emacs:

- Philippe Morel & Jean-Marc Vandel for early and late testing respectively.
- Jukka Partanen, Alan Bair, Michael Witbrock, Hugh D. Gamble and several
others for beta-testing.

Please send any bug reports, enhancement requests, etc to:

Post:                E-mail:
David Gay            [e-mail]
19 Chemin de la Source
CH-1296 Coppet
Vaud
Switzerland

8. Ordering Information
-----------------------

I can provide a complete copy of my development directory, which
includes:

o the standard emacs-18.58 files
o modified and new lisp files
o Amiga-specific source, as text and in RCS format (highlighting the
changes from a standard unix distribution, and the different versions).
o assorted lisp packages hacked for the Amiga (I will be posting some
of these in due course):
  - a tags-like access to the 2.0 autodocs (you must already have a
    copy of these ...)
  - gnus (a news reader) for use with Matt Dillon's uucp package.
  - getris, a tetris clone for emacs

All these as a tar file on a QIC-150 tape, for $200 (the same price as
the FSF, so as not to undercut them), or 300SF. This price is valid
until the 31st December 1993, and includes shipping by surface mail.

Please send all orders, by postal mail, to

  David Gay
  19 Chemin de la Source
  CH-1296 Coppet
  Vaud
  Switzerland

  Tel: +(41)-22 776 35 81 [Evenings, Central European Time]
  Fax: +(41)-22 776 70 58

Include with your order:
- A cheque, in dollars or Swiss francs.
- Your *complete* address (don't forget the country, etc).
- A phone or fax number so I can contact you if I have any problems.

I will be glad to include, on request, and with full source, some
other pieces of software I have written:
- An HP11 calculator (this is an update to the version available on
fish disks, with some bug fixes and 2.0 specific features).
- A scheme compiler for the Amiga, still in an alpha state.
- A fortune cookie program, including 1 megabyte of cookies (merged
from various sources).


Dvaid Gay
[e-mail]
Ecole Polytechnique Federale de Lausanne - Switzerland
Laboratoire d'Informatique Technique